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PREFACE 



This publication describes in general terms the Assembler H 
Version 2, Release 1.0, Program Product 5668-962 (hereafter 
referred to as Assembler H or, simply, assembler). It contains 
information about Assembler H extensions to VS Assembler, as well 
as differences between Assembler H Versions 1 and 2, to help 
prospective users evaluate and plan for the use of Assembler H 
Version 2 . 



ORGANIZATION OF MANUAL 



This manual contains the following chapters-* 

"Chapter 1. Introduction" describes the Assembler H language and 
tells how to modify it when you add it to your system. 

"Chapter 2. Macro and Conditional Assembly Language Extensions" 
tells about significant enhancements in the macro and conditional 
assembly language used by Assembler H. 

"Chapter 3. Basic Assembler Language Extensions" tells about 
enhancements to the basic assembler language used by Assembler H. 

"Chapter 4. Diagnostic Extensions" tells about the many 
diagnostic features that Assembler H provides to aid in the 
location and analysis of program errors. 

"Chapter 5. Factors Influencing Improved Performance" discusses 
the relationship of input/output operations and machine 
instructions on performance. 



ASSEMBLER H READING LIST 



The following documentation will be available to users of the 
program when the product is available' 

• Assembler H Version 2 Application Programming' Guide 

* Assembler H Version 2 Application Programming' Language 
Reference 

* Assembler H Version 2 Installation 

• Assembler H Version 2 Logic 
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SUMMARY OF AMENDMENTS 



DECEMBER 1981 



VERSION 2, RELEASE 1.0 



New features provided by the Assembler H Version 2 Program Product 
are'- 

• A program using System/370 Extended Architecture (S/370-XA) 
machine instructions may be assembled with Assembler H under 
MVS/Extended Architecture (MVS/XA), 0S/VS2 MVS Release 3.8, 
0S/VS1 Release 7, MVS/SP VI, VM/XA Migration Aid, or 
VM/System Product (VM/SP). However, a program using Extended 
Architecture instructions can only be executed on an Extended 
Architecture mode processor under MVS/XA or MVS/XA guest 
operating system under VM/XA Migration Aid. 

• An AMODE attribute allows specification of the entry point of 
the addressing mode (24-bit, 31-bit, or either 24- or 31-bit 
addresses) to be associated with a control section. 

• An RMODE attribute allows specification of the residence mode 
(in the 24-bit addressable range or anywhere) to be 
associated with a control section. 

• New channel command word instructions 1 CCW1 (format 1) allows 
31-bit data addresses; CCWO (format 0) allows 24-bit data 
addresses. 

• New machine instructions for the Extended Architecture mode 
processor; in addition, the System/370 (S/370) set of machine 
instructions has been expanded. A changed installation option 
allows users to specify whether the S/370, Extended 
Architecture, or Universal (all inclusive) instruction set 
will be used for assemblies. 

• Three new instruction types are included for the Extended 
Architecture object code* E, RRE, and SSE. 

• An underscore character is allowed in ordinary symbols. 

• Operation in the CMS environment of VM/SP and VM/XA Migration 
Aid. 
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CHAPTER 1. INTRODUCTION 






Assembler H Version 2 is an IBM program product that runs under 
MVS/Extended Architecture (MVS/XA), 0S/VS2 MVS Release 3.8, 
05/VS1 Release 7, MVS/SP Vl> VM/XA Migration Aid, and VM/SP. 
Version 1 of Assembler H made major extensions to the basic 
assembler language processor, and Version 2 has added new 
improvements that are listed in the following section. 

Assembler H Version 2 is required for installation of MVS/System 
Product Version 2 (MVS/SP V2) and Data Facility Product Release 1 
(5665-284), and for subsequent maintenance of the MVS/XA 
operating system. It is also required for installation of service 
and modifications to VM/XA Migration Aid. 



IMPROVEMENTS OVER OS ASSEMBLER H VERSION 1 



Assembler H Version 2 (5668-962) enables a program using 
System/370 Extended Architecture (S/370-XA) machine instructions 
to be assembled with Assembler H under any of the operating 
systems mentioned above. However, a program using Extended 
Architecture instructions can only be executed on an Extended 
Architecture mode processor under MVS/XA or MVS/XA guest 
operating system under VM/XA Migration Aid. 

Version 2 is a functional replacement for and incorporates all the 
functions available in OS Assembler H Version 1, Release 5.0 
(5734-AS1) . 

New features in Version 2 are: 

• An AMODE attribute allows specification of the entry point of 
the addressing mode (24-bit, 31-bit, or either 24- or 31-bit 
addresses) to be associated with a control section. 

• An RMODE attribute specification of the residence mode (in 
the 24-bit addressable range or anywhere) to be associated 
with a control section. 

• New channel command word instructions 1 CCW1 (format 1) allows 
31-bit data addresses; CCWO (format 0) allows 24-bit data 
addresses . 

• New machine instructions for the Extended Architecture mode 
processor; in addition, the IBM System/370 (S/370) set of 
machine instructions has been expanded. You may now specify 
at installation time whether the Extended Architecture, 
S/370, or Universal (all inclusive) instruction set will be 
used for assemblies. 

• Three new instruction types are included for the Extended 
Architecture object code: e, RRE, and SSE. 

• An underscore character is allowed in ordinary symbols. 

• Operation in the CMS environment of VM/System Product (VM/SP) 
and VM/Extended Architecture (VM/XA) Migration Aid. 



LANGUAGE COMPATIBILITY 



The language used by Assembler H Version 2, Release 1.0, has 
functional extensions to the language supported by VS Assembler 
and OS Assembler H Version 1, Release 5.0. Programs written for 
Assembler and OS Assembler Version 1, Release 5.0, that were 
successfully assembled with no warning or diagnostic messages, 
will be assembled correctly by Assembler H Version 2, Release 1. 



VS 
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PERFORMANCE 



The high-speed assembly capability of Assembler H relative to VS 
Assembler is a result of the following factors: 

• All text processing is performed in virtual storage if the 
region allocated to the assembler is sufficiently large. 

• The number of source text passes is reduced. 

• Multiple assemblies can be performed under the control of one 
set of job control cards (in one job step). 

• Conditional assembly instructions can be used to bypass macro 
definitions included in the source text. 



SYSTEM REQUIREMENTS 



Operating Envi ronments ; Assembler H operates under MVS/XA, OS/VS 
MVS 3.8, 0S/VS1 Release 7, MVS/SP VI, VM/XA Migration Aid, and 
VM/SP. 



Vi rtual Storag e - Assembler H Version 2, 
minimum of 200K bytes of main storage. 



Release 1.0, requires a 



Machine Regui rements ^ Version 2 is designed to operate on the IBM 
System/370, 303x, 3081, and 43xx processors supported by the 
above operating systems. 

Note: One 2400 or 3400 series tape unit is required for 
installation. The 2400 series tape unit is not, however, 
supported by MVS/XA. 



Auxiliary Storage Space ; 
the following data sets: 



Auxiliary storage space is required for 



• System input 

• Macro instruction library — either system or private or both 

• An intermediate work file, which must be a direct access 
device (3330/3333, 3340/3344, 3350, 3375, or 3380). Under 
VM/XA Migration Aid, the intermediate work file must be 
formatted as a CMS minidisk. Under VM/SP, the intermediate 
work file, which must be a direct access device (3310, 3370, 
or one of the devices mentioned above), must also be formatted 
as a CMS minidisk. 

• Pri nt output 

Library Space •• In terms of the IBM 3350 Direct Access Storage 
Facility, cataloged procedures for Assembler H require a maximum 
of one track on SYS1 .PROCLIB and the Assembler H load modules need 
approximately 15 tracks on SYSi.LINKLIB or a private iink 
1 i brary . 

Installat i on '- Version 2 is installed using System Modification 
Program, Release 4 (SMP4) for installations using 0S/VS2 MVS 
Release 3.8, MVS/XA, MVS/SP VI, or 0S/VS1, Released. 
Installation on CMS with VM/SP or VM/XA Migration Aid is 
accomplished by loading the program from tape with VMFPLC2 (a 
standard VM/SP utility). 
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INTERNAL DESIGN 



The internal organization of Assembler H provides for only two 
source text passes, in contrast with more for other assemblers. 
The first pass of the source text by Assembler H edits and expands 
macros, and builds dictionaries and the symbol table. The second 
pass completes the assembly and produces the desired output. 



Assembler H Version 2' General Information 



RESOLVING SYMBOL ATTRIBUTE REFERENCES 



The symbol table is built as symbols are encountered in macro 
generation and open-code assembly. If an attribute reference is 
made to a previously undefined symbol, Assembler H proceeds with a 
forward scan, called "lookahead" mode, of the source text. It 
continues the forward scan until the symbol that initiated the 
scan is resolved or until the end of the source program is 
encountered . 

During the scan, the assembler conditionally places all other 
symbols that are encountered into the symbol table. This avoids 
further forward scans unless a forward reference is made to a 
symbol at some point beyond the previous forward reference. The 
symbol attributes established by the forward scan are not fixed, 
however, and can be overridden when the symbol is placed in the 
symbol table as a result of regular assembly. If the symbol that 
initiated the forward scan is not found, a diagnostic message is 
i ssued. 



INTERNAL TEXT PROCESSING 






If the region allocated to the assembler is large enough to 
contain the text, Assembler H processes all intermediate assembly 
text in virtual storage. There is no limit to the region size that 
can be used efficiently by Assembler H, provided that the source 
module is large enough. 

Within the region allocated for an assembly of a source program, 
the amount of working storage Assembler H uses to perform an 
operation can dynamically expand to meet the storage requirements 
of that operation. When one block of working storage is filled 
with processed text, processing continues with the allocation of 
another block from within the region acquired for the assembly. 

As blocks of working storage am filled with processed text, they 
are flagged to indicate whether they can be written out to the 
external work file (SYSUT1). Partially filled blocks and those 
blocks taken up by the symbol table must remain in virtual storage 
at all times during the assembly. Those blocks that can be written 
out are put on the work file, but the blocks of text are also 
retained in working storage and continue to be effective for all 
assembly purposes. Only when all unallocated work space within 
the region is exhausted are the written-out text blocks in working 
storage reinitialized and overlaid with newly processed text. 
Then, when needed, the overlaid blocks of text are accessed from 
the work f i le. 

Note* If all blocks of working storage are allocated and flagged 
as resident when an operation requires additional work space, the 
assembly is terminated. Such assemblies must either be broken 
into subroutines or be assembled in a larger region. 



MODIFYING ASSEMBLER H WEN ADDING IT TO YOUR SYSTEM 



You can make several optional modifications to tailor Assembler H 
to fit the requirements of your installation. These modifications 
allow you to alter the default values for assembler options, to 
change the DD names for assembler data sets, and to choose the 
machine instruction set you want the assembler to support. You 
make the modifications when the assembler is added to your system, 
using an option-setting routine that is provided with the 
assembler. This routine is used only if you want to specify 
default options other than the standard options specified in the 
assembler when it is delivered to you. This section describes the 
modifications you can make to Assembler H. 
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DEFAULTS FOR ASSEMBLER H OPTIONS 



When you call the assembler with the EXEC job control statement* 
you can specify values for assembler options in its PARM field to 
override the standard values set in the assembler. Standard 
values for the options are set at delivery? however, they can be 
respecified by your installation when the assembler is added to 
your system. The options are= 



Standard Value 

DECK 

NOOBJECT 

LIST 

XREF (FULL) 

NORENT 

NOTEST 

NOBATCH 

ALIGN 

ESD 

RLD 

TERM 

LINECOUNT (55) 

FLAG (0) 



Alternate Value 

NODECK 

OBJECT 

NOLIST 

XREF (SHORT), NOXREF 

RENT 

TEST 

BATCH 

NOALIGN 

NOESD 

NORLD 

NOTERM 

LINECOUNT (a value in the range 1-99) 

FLAG (a value in the range 0-255) 



SYSPARM () (null string) SYSPARM (a string of 1-255 characters) 

Note! Because of job control language restrictions, if you use 
the PARM field of the EXEC statement to specify a SYSPARM value, 
the maximum length you can use is 56 characters. 

Your installation can also remove certain options, so that they 
cannot be specified. For example, you may want to change the 
standard value from DECK to NODECK and remove DECK so that it 
cannot be specified. 



DATA DEFINITION NAMES FOR ASSEMBLER H DATA SETS 

Assembler H requires the following data set DD names: 



v_y 



SYSIN 
SYSLIB 

SYSLIN 

SY5PRINT 

SYSPUNCH 

SYSUT1 

SYSTERM 



(if library members are called 

or COPY statements) 

(if OBJECT is specified) 

(if LIST is specified) 

(if DECK is specified) 

(if TERM is specified) 



by macro instructions 



Any of these names can be changed when the assembler is added to 
your system. For example, you may wish to replace SYSUT1 with 
WORK001, SYSIN with SYSIHPUT, etc. 



INSTRUCTION SET OPTIONS 



The instruction set, or operation code table available to 
Assembler H can be specified when the assembler is added to your 
system. Three instruction sets are available'- System/ 370 (S370), 
Extended Architecture (EXT), and Universal (UNIV), which 
incorporates both of preceding sets. 

The Extended Architecture object code includes three new 
instruction types called E, RRE, and SSE. Machine instructions of 
the new types are invoked by means of mnemonics and specified like 
other machine instructions. Most of the new instructions for the 
Extended Architecture have the same instruction types as the 
S/370 instructions. However, several have one of the new types. 
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CHAPTER 2. MACRO AND CONDITIONAL ASSEMBLY LANGUAGE EXTENSIONS 



Many restrictions imposed by VS Assembler are relaxed or 
eliminated by Assembler H to increase flexibility and extend 
language functions. For example, many ordering restrictions are 
removed from conditional assembly statements in macro definitions 
and i n open code. 

MACRO LANGUAGE EXTENSIONS 

Additional functions of the macro definition and macro 
instruction provided in Assembler H improve programmer control 
and coding flexibility. For example* macro definitions can appear 
anywhere in your source module; they can even be nested within 
other macro definitions. They can also be redefined at a later 
point in your program, and macro instruction operation codes can 
be generated by substitution. 

Note: The only restriction Assembler H imposes on the placement 
of macro definitions is that the macro definition must be 
encountered before it is called. 

GENERAL ADVANTAGES IN USING MACROS 

You can think of a macro definition as a subrout i ne whi ch can be 
modified each time it is called by a macro instruction. In 
modifying this subroutine, the assembler uses values passed in 
the macro instruction (for symbolic parameters). Further, the 
assembler uses values passed from other macros or from open code 
(global SET symbols) and data attribute references. The modified 
subroutine is included in your program in basic assembler 
language format; the assembler then processes it in the same way 
as any other source statements. By varying the symbolic 
parameters and global SET symbols, you can vary the generated 
assembler instructions and the sequence in which they are 
generated. 

Using macros gives you a scope similar to what you have when using 
a problem-oriented language. In fact, you can use macros to create 
your own language, tailored to your specific applications. 

EDITING MACRO DEFINITIONS 

The initial processing of a macro definition is called editing. 
Editing of a macro involves, among other things, checking of the 
syntax of the instructions and changing the source statements to 
special edited text used throughout the remainder of the 
assembly. The edited version of the macro definition is used to 
generate assembler language statements when the macro is called 
by a macro instruction. Therefore, a macro must always be edited 
before it can be called by a macro instruction. 

Assembler H allows you to use conditional assembly statements to 
avoid editing of certain macros. In the following example, the 
macro definition for MACSHOW is bypassed and not edited if the 
value of the system parameter (&SYSPARM) is NOTMACSHOW. Any macro 
instructions calling the macro are invalid. 

Name Operation Operand 

AIF ('&SYSPARM' EQ 'NOTMACSHOW' ) . PASS 

MACRO 

MACSHOW 

MEND 
.PASS ANOP 

Chapter 2. Macro and Conditional Assembly Language Extensions 5 



REDEFINING MACROS 



A macro definition can be redefined at any point in your source 
module. When a macro is redefined, the new definition is effective 
for all subsequent macro instructions that call it. 



Once a macro has been redefined by a macro definition, its 
previous function is lost, unless, prior to redefinition, the 
operation is assigned to another symbol with an OPSYN 
instruction. Later, if you wish the initial function of the 
operation code to be reestablished, you can include another OPSYN 
instruction to redefine it. The following example illustrates 
t h i s * 



Name 



Operation Operand 



MAC2 



MACRO 
MAC1 

MEND 

OPSYN 
MACRO 
MAC1 

MEND 



MAC1 



The symbol MAC1 is assigned as the 
name of this macro definition. 



MAC2 is assigned as an alias for MAC1 

MAC1 is assigned as the name of this 
macro definition. 



MAC1 



OPSYN 



MAC2 MAC1 is assigned to the first defini 
tion. The second definition is lost. 



You can also reestablish a previous source macro definition by 
issuing a conditional assembly branch (AGO or AIF) to a point 
prior to the initial definition of the macro. Than that definition 
will be edited and effective for subsequent macro instructions 
calling it. Consider the following example 1 



Name 

.UP 



Operation Operand 



ANOP 

MACRO 

MAC1 



Assign MAC1 to first macro definition 



MEND 



MACRO 
MAC1 



Assign MAC1 to second definition. 



NESTING MACRO DEFINITIONS 



MEND 

AGO .UP Branch to a point prior to first 
def i ni t i on . 



Assembler H allows both inner macro instructions and inner macro 
definitions. The inner macro definition is not edited until the 
outer macro is generated as the result of a macro instruction 
calling it, and then only if the inner macro definition is 
encountered during the processing of the outer macro. Thus, if the 
outer macro is not called, or if the inner macro is not 
encountered in the generation of the outer macro, the inner macro 
definition is never edited. Figure 1 on page 7 illustrates the 
editing of inner macro definitions. 
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MACRO 
MAC 3 

• 

MEND 



MEND 



Edited when 
MAC 2 is 
"called and 
generated 




Edited when 
MAC 1 is 
"called and 
generated 



Edited when 
"first encountered 






Figure 1. Editing Inner Macro Definitions 



First MAC1 is edited, and MAC2 and MAC3 are not. When MAC1 is 
called, MAC2 is edited (unless it is passed by an AIF or AGO 
branch); when MAC2 is called, MAC3 is edited. No macros can be 
accessed by a macro instruction until they have been edited. 

There is no limit to the number of nestings allowed for inner 
macro definitions. 



GENERATED MACRO INSTRUCTION OPERATION CODES 



Macro instruction operation codes can be generated by 
substitution, either in open code or inside macro definitions. 
Consider the following example: 

Name Operation Operand 



MACRO 
MAC 



tx 



MEND 

MACRO 

MACAU 

MEND 
MAC 



A,B,C Inner macro instruction 



MACALL Outer macro instruction 
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ARBITRARY LANGUAGE INPUT — AREAD 



The AREAD assembler operation permits a macro to "read cards" 
directly from the source stream into SETC variable symbols. The 
card image is assigned in the form of an 80-byte character string 
to the symbol specified in the name field of the instruction. 
Figure 2 illustrates how the instruction is used* 



3 



The macro instruction MAC 
causes the macro MAC to be 
processed. When the AREAD 
instruction is encountered, 
the next sequential card 
following the macro instruction 
is read and assigned to the 
SETC symbol &S. 



Open Code 



%J MAC 

^JjOHN L. SMITH, 




Macro Definition 

© 

^ MACRO 
MAC 

&S AREAD 

MEND 



&S: UOHN. ./-■ .SHITrt 1 

6 12 80 



Figure 2. AREAD Assembler Operation 



Repeated AREAD statements read successive cards 
Name Operation Operand 



&N 

&K+1 Increment loop counter 

(&K LT &N).L00P Check loop counter 



MACRO 
MAC 

.LOOP ANOP 
IK SETA 

&SUK) AREAD 
AIF 

MEND 

MAC 2 

JOHN L. SMITH 
HECTOR S. BROWN 

END 

The coding in this example assigns to the SETC symbol element 
XSC1) an 80-character string of JOHN L. SMITH followed by 67 
blanks; and to &S(2), HECTOR S. BROWN followed by 65 blank 
characters. 

When macro instructions are nested, the cards read by AREAD always 
v ave to follow the outermost macro instruction regardless of the 
1 ~*vel of nesting in which the AREAD instruction is found. Consider 
the following 1 
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Listing Options 



D 



MACRO 
MACIN 

XF AREAD 

MEND 

MACRO 

MACOUT 

MACIN 
THIS CARD IS NOT READ BY AREAD 

MEND 
MACOUT 
THIS CARD IS READ BY AREAD IN MACIN 

If the macro instruction containing the AREAD instruction is 
found in code included by the COPY instruction, source cards are 
read from the code brought in by the COPY instruction until end of 
file is reached, then from the input stream. 

Note: Cards that are read in by the AREAD instruction are not 
checked by the assembler. Therefore, no diagnostic will be issued 
if your AREAD statements read cards that are meant to be part of 
your source program. For example, if a macro containing an AREAD 
statement appears immediately before the END instruction, the END 
instruction is lost to the assembler. 



Normally, the AREAD input cards are printed in the assembler 
listing and assigned statement numbers. However, if you do not 
want them printed or assigned statement numbers, you can specify 
NOPRINT or NOSTMT in the operand of the AREAD instruction. 



AREAD/PUNCH Input/Output Capability 



The AREAD facility complements the PUNCH facility to provide 
macros with direct input/output capability. The total 
input/output capability of macros is as follows 1 

Implied Input: Parameter values and global SET symbol values 
that ar& passed to the macro 

Implied Output: Generated statements passed to the assembler for 
later processing 

Direct Input: AREAD 

Direct Output: MNOTE for printed messages; PUNCH for punched 
cards 

For example, you can use AREAD and PUNCH to write card conversion 
programs. The following macro interchanges the left and right 
halves of cards placed immediately after a macro instruction 
calling it. End of input is indicated with the word FINISHED in 
the first columns of the last card in the input to the macro. 



Name 


Operat 

MACRO 
SWAP 


ion 


Operand 


.LOOP 


ANOP 






&CARD 


AREAD 








AIF 




CSCARD'(1,8) EQ 'FINISHED') 


JcCARD 


SETC 




' &CARD(41,40), f &CARD f (1,40) 




PUNCH 




XCARD 




AGO 




.LOOP 


.MEND 


MEND 







MEND 
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MULTILEVEL SUBLISTS IN MACRO INSTRUCTION OPERANDS 



Multilevel sublists (sublists within sublists) are permitted in 
macro instruction operands and in the keyword default values in 
prototype statements, as shown in the following 1 

MAC1 (A,B,(W,X,(R,S,T),Y,Z),C,D) 
MAC2 £KEY=(1,12,(8,4),64) 

The depth of this nesting is limited only by the constraint that 
the total length of an individual operand cannot exceed 255 
characters. 

To access individual elements at any level of a multilevel 
operand, you use additional subscripts after &SYSLIST or the 
symbolic parameter name. For example, if &P is the first 
positional parameter and the value assigned to it in a macro 
instruction is ( A, (B, (C) ) > D) , then : 

&P = SSYSLIST(l) =(A,(B,(C)),D) 

SP(1) = SSYSLIST(1,1) =A 

&P(2) = &SYSLIST(1,2) =(B,(C)) 

&P(2,1) = &SYSLIST(1,2,1) =B 

&P(2,2) = &SYSLIST(1,2,2) =(C) 

SP(2,2,1) = XSYSLIST(1,2,2,1) =C 

&P(2,2,2) = SSYSLIST(1,2,2,2) =null 

N'«P(2,2) = N'4SYSLIST(1,2,2) =1 

N'&P(2) = N'£SYSLIST(1,2) =2 

N'&P(3) = N'&SYSLIST(1,3) =1 

N'&P = N'SSYSLISTCl) =3 



REDEFINING CONDITIONAL ASSEMBLY OPERATION CODES 



You can use the OPSYN instruction to redefine operation codes 
anywhere in your source module. The new definitions of operation 
codes then remain in effect for all subsequent statements, 
including those generated from macros. However, the definitions 
of conditional assembly statements are fixed when the macro 
definition is edited. Thus, OPSYN statements placed after a 
definition of a macro have no effect on the conditional assembly 
statements of that macro, if it is called later in the source 
code. Consider the following example"* 

Name operation Operand comment 

MACRO Macro header 

MAC . . . Macro prototype 

AIF 
MVC 





MEND 




Macro trai ler 


AIF 
MVC 


OPSYN 
OPSYN 


AGO 
MVI 


Assign AGO properties to AIF 
Assign MVI propt?rt i e*> to MVC 




MAC 
CAIF 




Macro call 

Evaluated as AIF instruction 



Generated AIFs not printed] 
+ MVC ... Evaluated as MVI instruction 

Open code started at this point 
AIF ... Evaluated as AGO instruction 

MVC ... Evaluated as MVI instruction 

In this example, AIF and MVC instructions are used in a macro 
definition. OPSYN statements are used to assign the properties of 
AGO to AIF and to assign the properties of MVI to MVC. In 
subsequent generations of the macro involved, AIF is still 
defined as an AIF operation, and MVC is treated as an MVI 
operation. In open code following the macro call, the operations 
of both instructions are derived from their new definitions 
assigned by the OPSYN statements. If the macro is redefined (by 
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another macro definition), the new definitions of AIF and MVC 
(that is, AGO and MVI) are fixed for any further expansions. 

Notes Because the assembler does not edit inner macro definitions 
until it encounters them during the processing of a macro 
instruction calling the outer macro, this description does not 
apply to nested macro definitions. An OPSYN statement placed 
before the outer macro instruction will affect conditional 
assembly statements in the inner macro definition. 



OTHER LANGUAGE EXTENSIONS 



The following rules apply to other language extensions of 
Assembler H relative to the VS Assembler^ 

• Macro names, variable symbols (including the ampersand), and 
sequence symbols (including the period), can be a maximum of 
63 alphameric characters. The first character must be 
alphabetic, not an ampersand or a period. 

• Comments (both '*' and *.*' types) can be inserted between the 
macro header and the prototype and, for library macros, 
before the macro header. Any such comments are discarded by 
the macro-edit phase and are not printed with the generation 
of the macro. 

• Any mnemonic operation code of the S/370, Extended 
Architecture, and Universal instruction sets, or any 
assembler operation code, can be defined as a macro 
instruction. When one of the operation codes is redefined as a 
macro instruction, subsequent use is interpreted as a macro 
call. 



Any instruction, except ICTL, 
def i ni ti on. 



is permitted within a macro 



CONDITIONAL ASSEMBLY INSTRUCTION EXTENSIONS 



AIF STATEMENTS 



The flexibility of the AIF, AGO, SETA, SETB, and 5ETC instructions 
is increased in Assembler H. Multiple AIF statements can be merged 
in one AIF statement, the AGO statement has an expanded 
interpretive function, and a single SETx instruction (meaning 
SETA, SETA, or SETC) can assign values to more than one element of 
a SET symbol array. Format and ordering restrictions are also 
revised, and a new system variable symbol is introduced. In 
addition, generated statements have new functions, and the 
availability of symbol attributes is increased. 



The AIF statement can include a string of logical expressions and 
related sequence symbols. There is no limit to the number of 
expressions and symbols that you can use in an extended AIF 
statement. The format is : 



Operation Operand 



AIF 



(logical expressi on) . SI , 
(logical expressi on) . S2 , 
...,(logical expressi on) . Sn 



Column 72 

X 

X 



This is equivalent to "n" successive AIF statements. The branch is 
taken to the first sequence symbol (scanning left to right) that 
corresponds to a true logical expression. If none of the logical 
expressions is true, control passes to the next sequential 
i nstructi on . 
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AGO STATEMENTS 



One AGO statement can contain computed branch sequence 
information. The extended AGO statement has the following format 

Operation operand 



AGO 



(K).S1, .S2, . . ., .Sn 



where "K" is a SETA arithmetic expression. If the value of "K" 
lies between 1 and "n" inclusive, then the branch is taken to the 
"Kth" sequence symbol in the list. If "K" is outside that range, 
no branch is taken. The statement is exactly equivalent to the 
following sequence of AIF instructions* 



Operation Operand 



AIF 
AIF 



(arithmetic expression 
(arithmetic expression 



EQ D.S1 
EQ 2).S2 



AIF 



(arithmetic expression EQ n).Sn 



SETX STATEMENTS 



The SETA, SETB, and SETC statements are used to assign arithmetic, 
binary, and character values, respectively, to SET variable 
symbols. You can use the SET statement to assign lists or arrays 
of values to subscripted SET symbols. For example, a list of 100 
SETx values can be coded in one extended SETx statement. The 
extended SETx statement has the following format ' 



Name 
&SYMCK) 



Operation Operand 



SETx 



XI, Xii, ,Xh, . . . ,Xn 



The form of the name and operation fields is the same as that used 
in the VS Assembler for assignment of a dimensioned variable SET 
symbol ? &SYM is a dimensioned SET symbol, "K" is a SETA 
arithmetic expression, and SETx is SETA, SETB, or SETC. Each of 
the operands ("Xn") has the form of an ordinary SETx operand, or 
may be omitted. Whenever an operand is omitted, the corresponding 
element of the dimensioned variable SET symbol (&SYM) is left 
unchanged. 

When none of the operands is omitted, the SETx statement is 
equivalent to the following sequence of statements? 






Name 

fcSYM(K) 
&SYM(K+1) 



Operation Operand 



SETx 
SETx 



XI 
X2 



&SYM(K+n-l) SETx Xn 
Following are examples of the use of extended SETx statements? 
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*X(3) SETA 3, ,5, ,7 

This is equivalent to the sequence 1 



SX(3) 


SETA 


3 


&X(5) 


SETA 


5 


&X(7) 


SETA 


7 



2. &X(1) SETA 1,&X(1)+1,4X(2)+1 

This is equivalent to the sequence: 

&X(1) SETA 1 

&X(2) SETA 2 

&XC3) SETA 3 

3. &Y(1) SETC ",," 

This sets &Y(1) and &Y(3) to null values and leaves & Y C 2 ) 
unchanged. 



SET SYMBOL FORMAT AND DEFINITION CHANGES 



CREATED SET SYMBOLS 



Assembler H extensions to SETx statements, and local and global 
definition statements, are discussed in the following list; 

• Global and local SET symbol declarations are processed at 
generation time in the assembly process. Either a macro 
definition or open code can contain more than one declaration 
for a given SET symbol, as long as only one is encountered 
during a given macro expansion or conditional assembly of 
open code. 

• A SET symbol that has not been declared in a LCLx or GBLx 
statement is implicitly declared by appearing in the name 
field of a SETx statement. Such a declaration is interpreted 
as local, with the type determined by the SETx operator, and 
the dimensionality is determined by the occurrence of a 
subscript in the name field. Any explicit declaration 
encountered thereafter is flagged as a duplicate declaration. 

• A SET symbol can be defined as an array of values by adding a 
subscript after it, when it is declared, either explicitly or 
implicitly. All such SET symbol arrays are open-ended; the 
subscript value specified in the declaration does not limit 
the size of the array. This is shown in the following example 1 

Name operation operand 

LCLA &JC50) 
&J(45) SETA 415 Allowed under both assemblers 
&JC89) SETA 38 Allowed only under Assembler H 



SET symbols may be created during the generation of a macro. A 
created SET symbol has the form &(e), where "e" represents one or 
more of the following 1 

• Variable symbols, optionally subscripted 

• Strings of alphameric characters 

• Created SET symbols 

After substitution and concatenation, "e" must consist of a 
string of 1 to 62 alphameric characters, the first being 
alphabetic. This string is then used as the name of a SETx 
variable. For example: 
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Name Operation operand 

SY(1) SETC 'Al' ,'A2 , ,'A3', , A4' 
&(&Y(3)) SETA 5 

These statements have an effect similar to &A3 SETA 5. 

Created SET symbols can be used wherever ordinary SET symbols are 
permitted* including declarations; they can even be nested in 
other created SET symbols. The following nested variable could 
generate a valid created SET symbol: 

&UC4XUUY)))) 

The created SET symbol can be thought of as a form of indirect 
addressing. Thus, in the first example above, &Y is a variable 
whose value is the name of the variable to be updated. With nested 
created SET symbols, you can get such indirect addressing to any 
level . 

Created SET symbols can also offer an "associative memory" 
facility. For example, a symbol table of numeric attributes can be 
referenced by an expression of the form &C&SYM) (&I) to yield the 
"Ith" element of the symbol substituted for &SYM. 

A related application is illustrated in the following macro 
definition. This macro is designed to push an item into the 
specified pushdown stack. A new stack is created for each new 
stack name given as a parameter in the macro call. Note that &LIST 
becomes as long as required. 

MACRO 

PUSHDOWN &STAK,&ITEM 

GBLA &(&STAK)(1),&USTAK.SIZE) 

&USTAK.SIZE) SETA U8STAK. SIZE) + 1 

&USTAK)UUSTAK.SIZE)) SETA &ITEM 

MEND 

The macro call "PUSHDOWN LIST, 25" is logically equivalent to: 

GBLA *LIST(1),&LISTSIZE 
LISTSIZE SETA &LISTSIZE+1 

LISTULISTSIZE) SETA 25 

Created SET symbols also enable you to get some of the effect of 
multidimensional arrays by creating a separate named item for 
each element of the array. For example, a three-dimensional array 
of the form &X(&I,&J,&K) can be addressed as &CX&I . $&J . $&K) . Then 
&X(2,3,4) would be represented as a reference to the symbol 
&X2$3$4. 

Note that what is being created here is a SET symbol. Both 
creation and recognition occur at macro generation time. In 
contrast, parameters are recognised and encoded (fixed) at macro 
edit time. Consequently, if a created SET symbol name happens to 
coincide with a parameter name, the fact is ignored and there is 
no interaction between the two. 



USING SETC VARIABLES IN ARITHMETIC EXPRESSIONS 



You can use a SETC variable as an arithmetic term if its character 
string value represents a valid self-defining term. A null value 
is treated as zero. This allows you to associate numeric values 
with EBCDIC or hexadecimal characters, and can be used for such 
applications as indexing, code conversion, translation, or 
sort i ng. 

For example, the following set of instructions converts a 
hexadecimal value in &X into the decimal value 243 in &VAL. 
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Name 

ax 

&VAL 



Operation 

SETC 
SETC 



Operand 

! X f T F3 lf 

&x 



ATTRIBUTE REFERENCES 



Attributes of symbols produced by macro expansion or substitution 
in open code are available immediately after the statement 
referenced is generated. 



Forward Attribute Reference 



If an attribute reference is made to a symbol that has not yet 
been encountered, the assembler scans the source code either 
until it finds the referenced symbol in the name field of a 
statement in open code, or until it reaches the end of the source 
module. The assembler makes entries for the symbol, as well as any 
other not previously defined symbols it encounters during the 
scan, in the symbol table. The assembler does not completely check 
the syntax of the statements for which it makes entries in the 
symbol table. Therefore, a valid attribute reference may result 
from a forward scan, even though the statement is later found to 
be in error and therefore not accepted by the assembler. Further, 
you must be careful with the contents of any AREAD input in your 
source module. If the first word of an AREAD input card conflicts 
with an attribute reference, and if it appears before the "true" 
symbol, the forward scan will attempt to evaluate that card 
i nstead. 



Attribute Reference Using SETC Variables 






^L^ 



The symbol referenced by an attribute reference of type length 
CL'), type (T'), scaling (S'), integer (I 1 ), and defined CD', see 
below) can only be an ordinary symbol. The name of the ordinary 
symbol can, however, be specified in three different ways 1 

• The name of the ordinary symbol itself 

• The name of a symbolic parameter whose value is the name of 
the ordinary symbol 

• The name of a SETC symbol whose value is the name of the 
ordinary symbol 

Note: You can specify the underscore character in ordinary 
symbols; that is, symbols which can be used in the name and 
operand fields of machine and assembler instructions. It must not 
appear in an external symbol. 

Consider the following examples- 
Name Operation Operand 



&F 
ORDSYM 



SETC 
DC 



T» ORDSYM 
H'3' 



In this example, the symbol in the attribute specification 
(T'ORDSYM) is the ordinary symbol itself. 



Name 

IK 
&F 
ORDSYM 



Operation Operand 



SETC 
SETC 
DC 



•ORDSYM' 

T'&K 

H»3* 



In this example, however, the symbol in the attribute reference 
(T'&K) is a variable symbol whose value is the name of the 
referenced symbol (ORDSYM). The type attribute in both examples 
will be the type attribute of the DC instruction named ORDSYM. 
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Defined Attribute (D f ) 



The defined attribute (D f ) can be used in conditional assembly 
statements to determine if a given symbol has been defined at a 
prior point in the source module. If the symbol is already 
defined, the value of the defined attribute is one; if it has not 
been defined, the value is zero. By testing a symbol for the 
defined attribute, you can avoid a forward scan of the source 
code. 






Number Attributes for SET Symbols 



The number attribute can be applied to SETx variables to determine 
the highest subscript value of a SET symbol array to which a value 
has been assigned in a SETx instruction. For example, if the only 
occurrences of the SETA symbol &A are- 
Name Operation operand 

&A(1) SETA 

&A(2) SETA 

&A(3) SETA &A(2) 

&A(5) SETA 5 

4AC10) SETA 

then N f SA is 10. 

The number attribute is zero for a SET symbol that has not been 
assigned any value. 



ALTERNATE FORMAT IN CONDITIONAL ASSEMBLY 



Alternate format allows a group of operands to be spread over 
several lines of code. Each line, except the last, is followed by 
a comma, one or more blanks, and a character in column 72. 
Optionally, comments are inserted between the blank and column 
72. The last line terminates the series with a blank in column 72. 

The extended AGO and AIF, GBLx, LCLx, and extended SETx statements 
can also be written in alternate format, as shown in the following 
examples'* 

Name 



*B(1) 



Operation 


Operand 


Comment 




AGO 


(XA).Sl, 
.S2, .S3, 
.S*+ 


comment 


X 
X 


AIF 


(Ul).Sl, 
UL2).S2, 
(U3).S3 


comment 


X 
X 


GBLA 


SA1, 
&B(5) 




X 


LCLC 


LI, 

L2,L3, 

L4 


comment 
comment 
comment 


X 
X 


SETB 


0, 

UA NE 3), 

CSC EQ f XYZ') 


comment 
comment 


X 
X 



SYSTEM VARIABLE SYMBOLS 



System variable symbols are local variable symbols that are 
assigned values by the assembler when they are encountered. 
&SYSL0C is identical in function to &SYSECT, except that its value 
is the character string that represents the location counter (as 
controlled by the LOCTR statement) that is in effect at the time 
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the macro is called. &SYSECT gets the value of the current CSECT, 
DESECT, or COM section. If no LOCTR statement is in effect, the 
value of &SYSL0C is the same as the value of &SYSECT. &SYSL0C can 
be used only in macro definitions. The LOCTR instruction is 
described in "Changes to Program Sectioning and Linking 
Controls. " 



For example, when the following statements occur in a source 
program, &SYSL0C will have the character string value XYZ during 
expansion of MACl. 



Name 


Operation 


Operand 


&c 


MACRO 

MACl 

SETC 


'&SYSL0C 


XYZ 


MEND 

LOCTR 

MACl 





f*\ 
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CHAPTER 3. BASIC ASSEMBLER LANGUAGE EXTENSIONS 



This chapter covers the extensions to VS Assembler for 
Assembler H. 

R EVISED ASSEMBLER OPERATIONS 

Several assembler operations used in VS Assembler have been 
extended in Assembler H. The revised operations are described in 
the following sections. 

OPSYN INSTRUCTION EXTENSION 

You can code OPSYN instructions anywhere in your source module. 

EQU INSTRUCTION EXTENSION 

Symbols appearing in the first operand of the EQU instruction need 
not have been previously defined. Thus, in the following example, 
both WIDTH and LENGTH can be defined later in the source code*- 

Name Operation operand 

VAL EQU 40-WIDTH+LENGTH,4,F 

COPY INSTRUCTION EXTENSION 

Any number of "nestings" — COPY instructions within code that has 
been brought into your program by another COPY instruction — is 
permi tted. 

CNOP INSTRUCTION EXTENSION 

There is no restriction that symbols in the operand field of a 
CNOP instruction must have been previously defined. 

ISEQ INSTRUCTION EXTENSION 

Sequence checking of any column on input cards is allowed. 

NE» ASSEMBLER OPERATIONS 

New assembler operations have been added to Assembler H. The new 
operations are described in the following sections. 

ADDRESS MODE (AMODE) AND RESIDENCE MODE (RMODE) 

The AMODE and RMODE assembler attributes are included only in the 
Extended Architecture and Universal instruction sets ( no t in the 
S/370 instruction set). AMODE sets the entry point of the 
addressing mode, and RMODE, that of the residence mode. 

The format of the AMODE attribute contains a name field (which 
associates the addressing mode with a control section), the 
operation (AMODE), and one of three operands (24, 31, or ANY). 24 
specifies that an addressing mode within the 24-bit range is 
associated with the control section; 31, an addressing mode 
within the 31-bit range; and ANY, an addressing mode within either 
the 24- or the 31-bi t range. 
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The format of the RMODE attribute contains a name field (which 
associates the residence mode with a control section), the 
operation (RMODE), and one of two operands (24 or ANY). 24 
specifies that a residence mode within the 24-bit range is 
associated with the control section, and ANY, a residence mode of 
ANY. 

Any field of these attributes may be generated by a macro, or by 
substitution in open code. 

AMODE and RMODE attributes may be specified anywhere in the 
assembly. If the name field in either attribute is left blank, 
there must be an unnamed control section in the assembly. These 
attributes do not initiate an unnamed control section. 



CHANNEL COMMAND WORDS (CCW1 AND CCWO) 



Two new assembler instructions, CCW1 and CCWO, are included only 
in the Extended Architecture and Universal instruction sets. CCW1 
results in a Format 1 channel command word that allows a 31-bit 
data address; CCWO results in a Format channel command word that 
allows a 24-bit data address. 

Notes: 

1. The CCW instruction, which is included in all instruction 
sets, also results in a Format channel command word. The 
format of the CCW1 and CCWO instructions, like that of a CCW 
instruction, contains a name field, the operation, and an 
operand (which has a command code, data address, flags, and 
data count) . 

2. If EXCP or EXCPVR is used, only CCW or CCWO is valid, because 
EXCP and EXCPVR do not support 31-bit data addresses in 
channel command words. 

3. If RMODE ANY is used with CCW or CCWO, an invalid data address 
in the channel command word may result at execution time. See 
the Assembler H Version 2 Application Programming- Guide for 
other examples of restrictions concerning the use of RMODE 
ANY. 



ASSEMBLER LANGUAGE SYNT AX EXT ENS IONS 



CONTINUATION LINES 



The syntax of the assembler language deals with the structure of 
individual elements of an instruction statement and with the 
order in which the elements are presented in that statement. 
Several syntactical elements of the VS Assembler language are 
extended in the Assembler H language. 



Assembler H allows as many as nine continuation lines in an 
ordinary assembler language statement. 

The alternate format, which allows as many continuation lines as 
needed, is allowed for certain instructions. These include macro 
prototype statements and macro instruction statements, as well as 
AIF, AGO, SETx, LCLx, and GBLx instructions. 



SYMBOL LENGTH 



A maximum of 63 characters can be used for a symbol. This limit 
includes the ampersand for variable symbols and the period for 
sequence symbols. 

Because the linkage editor does not accept symbols longer than 8 
characters, external symbols are limited to 8 characters. 
External symbols are those used in the name field of START, CSECT, 
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COM, and DXD statements, and in the operand field of ENTRY, EXTRN, ^_^ 
and WXTRN statements. Symbols used in V- and Q-type address M ■ 

constants are also restricted to 8 characters. ^L y 



Ew CL Y u. I. %3 NX ! fli N C.Ar^ffvC.wSSXUr^S 



Any number of terms of levels of parentheses in an expression is 
allowed. 



ANOTHER LANGUAGE EXTENSION 



The following language extension has been made to Version 2 of 
Assembler H. 



UNDERSCORE IN SYMBOLS 



You can specify the underscore character in ordinary symbols, 
that is, symbols which can be used in the name and operand fields 
of machine and assembler instructions. 

The format of an ordinary symbol contains a one-byte alphabetic 
character followed by up to 62 alphameric or underscore 
characters. The underscore character must not appear in an 
external symbol. See the Assembler H Version 2 Application 
Programming 1 Guide for a list of symbol fields in which it must 
not appear. 



CHANGES TO PROGRAMMING SECTIONING AND LINKING CONTROLS 



Operations controlling program sectioning and linking are 
extended in Assembler H to allow increased freedom of program 
organisation. A new instruction is available, and several others 
have been revised. 



USE OF MULTIPLE LOCATION COUNTERS 



The assembler instruction LOCTR allows multiple location counters 
to be defined within a control section during the assembly. The 
format of this new instruction is- 

Name Operation operand 

Any ordinary LOCTR Blank 

or variable 

symbol 

The assembler assigns consecutive addresses to all segments of a 
location counter in a control section before it continues address 
assignment with the first segment of the next location counter. By 
using the LOCTR instruction, you can cause your program 
object-code structure to differ from the logical order appearing 
in the listing. You can code sections of a program as independent 
logical and sequential units. For example, you can code work areas 
and constants within the section of code that requires them, 
without branching around them. Figure 3 on page 21 illustrates 
thi s procedure. 
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WORKAREA LOCTR 

XXX DC XXX 

XXX DS XXX 
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MAINCODE. 






MAINCODE LOCTR 







Assembled with 

consecutive 

addresses 
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The following rules govern applications of the LOCTR instruction^ 

• A location counter can be interrupted by a CSECT, DSECT, COM, 
or another LOCTR instruction. 

• A control section name that is defined by the CSECT, COM, 
DSECT, or START instruction automatically names the first 
location counter in that section. 

• A LOCTR instruction with the same name as a control section 
resumes the first location counter in that section. 

• A LOCTR instruction with the same name as a previous LOCTR 
instruction forces a return to the control section in which it 
was first defined and resumes the particular counter 

i nvolved . 

• Resumption of a control section causes resumption of the last 
active, not necessarily the highest valued, location counter 
under that control section. 

• A control section name defined for the first time is in error 
if it is identical to a previously defined LOCTR instruction 
name . 

• A LOCTR instruction occurring before the first control 
section will initiate an unnamed CSECT before the LOCTR 
instruction is processed. 

• LOCTR instructions do not force location counter alignment. 



REVISION OF Q-TYFE ADDRESS CONSTANTS 



o 



Q-type address constants reserve storage for the offset of an 
external dummy section. Some restrictions have been relieved 
under Assembler H : 

• DXD or DSECT names referenced in Q-Type address constants do 
not require previous definition. 

• If the relocatable symbol in a DXD statement is not used in a 
Q-type address constant, the DXD symbol is not placed in the 
external symbol dictionary (ESD). DXD statements without a 
Q-type address constant reference are not addressable by the 
program. 
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NUMBER OF ESD SYMBOLS 



There is no restriction on the number of symbols that can be 
contained in the external symbol dictionary (ESD). The maximum 
number of entries depends on the amount of main storage available 
to the linkage editor. 



i 
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CHAPTER 4. DIAGNOSTICS EXTENSIONS 



Assembler H has many diagnostic features to aid in the location 
and analysis of program errors. Refinement of macro and 
conditional assembly diagnostics is particularly significant. 
This chapter describes these diagnostic features. 



DIAGNOSTIC EXTENSIONS IN REGULAR ASSEMBLY 



ERROR MESSAGES 






Assembler H prints in-line error messages in the listing and 
includes at the end of the listing a total of the errors and a 
table of their line numbers. Certain in-line messages include a 
copy of the segment of the statement that is in error. Thus, error 
conditions are spelled out as they occur with direct reference to 
a specific error. The following example illustrates this. 

CSECT 

CO MM 
xx*ERRORX**UNDEFINED OP CODE - COMM 

DS (*+5)F 
xx*ERRORxx*RELOCATABILITY ERROR " (*+5)F 

1NAME DC F'0 f 
xx*ERRORXX*SYMBOL TOO LONG, OR 1ST CHARACTER NOT A LETTER - 1NAME 

&C SETC 'AGO* 
&C .X 
xx*ERROR*XXQP CODE NOT ALLOWED TO BE GENERATED - AGO 



END 
DIAGNOSTIC MESSAGES IN MACRO ASSEMBLY 



Diagnostic messages printed in macro-generated text are more 
descriptive than those in the VS Assembler. In addition, the macro 
level and the statement number of the macro definition are printed 
for each programmer macro instruction. The macro level and the 
first five characters (or fewer) of the macro name are printed for 
library macro expansions. 



SEQUENCE FIELD IN MACRO-GENERATED TEXT 



When a library macro definition is processed as a result of a 
macro call, the sequence field (columns 73 through 80) of the 
generated statements contains the level of the macro call in the 
first two columns, a hyphen in the third column, and the first 
five letters of the macro-definition name in the remaining five 
columns. When a line is generated from a source-program macro or a 
copied library macro, the last five columns contain the line 
number of the model statement in the definition from which the 
generated statement is derived. This information can be an 
important diagnostic aid when analyzing output dealing with macro 
calls within macro calls. 



FORMAT OF MACRO-GENERATED TEXT 






Whenever possible, a generated statement is printed in the same 
format as the corresponding macro-definition (model) statement. 
The starting columns of the operation, operand, and comments 
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fields are preserved unless they ar& displaced by field 
substitution, as shown in the following example' 



Source Statements: 
Generated Statement: 



IC SETC 
iC LA 
ABCDEFGHIJK 



'ABCDEFGHIJK' 

1,4 

LA 1,4 



ERROR MESSAGES FOR A LIBRARY MACRO DEFINITION 



Format errors within a particular library macro definition are 
listed directly following the first call of that macro. 
Subsequent calls on the library macro do not result in this type 
of diagnostic. If the appropriate option of the PRINT instruction 
is in effect, errors arising in the generated text of a library 
macro are listed in line within the generated text. The following 
example shows the placement of error messages. 



MACRO 
LIBMAC 

LCLA A 

SB SETA &A 

MEND 



**ERR0RH* 
**ERR0R** 



L i brary Macro 



LIBMAC 
INVALID LCLA OPERAND 

"UNDECLARED VARIABLE SYMBOL 



Fi rst 

LIBMAC 

Call 



**ERR0R*x 



LIBMAC 

'UNDECLARED VARIABLE SYMBOL 



Second 
LIBMAC 
Call 



ERROR MESSAGES FOR SOURCE PROGRAM MACRO DEFINITIONS 

Macro definitions contained in the source program are printed in 
the listing, provided that the appropriate PRINT options ar& in 
effect. In-line edit diagnostics ar& inserted in the listing 
directly following the statement in error. Errors analyzed during 
macro generation produce in-line messages in the generated text. 

ERROR MESSAGES IN MACRO-GENERATED TEXT 

Diagnostic messages in generated text generally include? 

• A description of the error 

• The recovery action 

• The model statement number at which the error occurred 

• A SET symbol name, parameter number, or value string 
associated with the error 



MACRO TRACE FACILITY (MHELP) 



The MHELP instruction controls a set of trace and dump facilities. 
Options are selected by an absolute expression in the MHELP 
operand field. MHELP statements can occur anywhere in open code or 
in macro definitions. MHELP options remain in effect continuously 
until superseded by another MHELP statement. MHELP options are: 
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Macro Call Trace 



Macro Branch Trace 



MHELP B'l' or MHELP 1 

This option provides a one-line trace 
for each macro call, giving the name of 
the called macro, its nested depth, and 
its &SYSNDX (total number of macro 
calls) value. This trace is provided 
upon entry into the macro. No trace is 
provided if error conditions prevent 
entry into the macro. 

MHELP B'10' or MHELP 2 



D 



Macro Entry Dump 



Macro Exit Dump 



Macro AIF Duwp 



Global Suppression 



MHELP Suppression 



MHELP Control on &SYSNDX 



This option provides a one-line trace 
for each AGO and true AIF conditional 
assembly statement within a macro. It 
gives the model statement numbers of 
the "branched from" and "branched to" 
statements, and the name of the macro 
in which the branch occurs. This trace 
option is suppressed for library 
macros. 

MHELP B'10000' or MHELP 16 

This option dumps parameter values from 
the macro dictionary immediately after 
a macro call is processed. 

MHELP B'1000' or MHELP 8 

This option dumps SET symbol values 
from the macro dictionary upon 
encountering a MEHD or MEXIT statement. 

MHELP B'100' or MHELP 4 

This option dumps SET symbol values 
from the macro dictionary immediately 
before each AIF statement that is 
encountered. 

MHELP B' 100000' or MHELP 32 

This option suppresses global SET 
symbols in the two preceding options, 
MHELP 4 and MHELP 8. 

MHELP B'10000000' or MHELP 128 

This option suppresses all currently 
active MHELP options. 

MHELP operands are assembled into a 
signed fullword. See the sample 
hexadecimal values for the MHELP 
operand (Figure 4 on page 26). 






MHELP and &SYSNDX values are determined according to the 
f ollowi ng rules : 

1. If there are any nonzero bits present in the low-order 6 bits 
of the MHELP field (see Figure 3 on page 21), the 
corresponding options are turned on. 

2. &SYSNDX values are set only if the &SYSNDX field has any 
nonzero bits in it. The value of &SYSNDX is the value of the 
entire fullword. If the &SYSMDX field contains only zeros, 
even if there is a value in the high-order bytes to the left 
of the &SYSNDX field, the &SYSNDX value is not set. 

When &SYSNDX (the total number of macro calls) exceeds the 
value of the fullword which contains the MHELP operand value, 
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4869 



0000 



13 



05 



Macro call trace, 
Macro AIF dump; 
&SYSNDX 4869 



65536 



0001 



00 



00 



No effect 



16777232 



0100 



00 



10 



Macro entry dump 



286-8 



0000 



70 



06 



Macro branch trace, 
Macro AIF dump; 
&SYSNDX 28678 



Figure 4. MHELP Control on 4SYSNDX 



control is forced to stay at the open-code level by, in 
effect, making every statement in a macro behave 1 i ke a MEXIT. 
Open-code macro calls are honored, but with an immediate exit 
back to open code. 

When the value of the &SYSNDX reaches its limit, a diagnostic 
message is issued. 

Note* Multiple options can be obtained by coding the option codes 
in one MHELP operand. For example, call and branch traces can be 
invoked by MHELP B'll', MHELP 2+1, or MHELP 3. 



ABNORMAL TERMINATION OF ASSEMBLY 



The assembler produces a specially formatted dump whenever an 
assembly cannot be completed. This may help you in determining the 
nature of the error. The dump is also useful if the abnormal 
termination was caused by an error in the assembler itself. 

\ 
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CHAPTER 5. FACTORS INFLUENCING IMPROVED PERFORMANCE 



D 



This chapter gives some of the factors used by Assembler H that 
cause performance to be improved relative to VS Assembler. The 
following list summarizes the factors that influence the number 
of input/output operations and machine instructions used by 
Assembler H. 

• Logical text stream and tables that are a result of the 
internal assembly process remain resident in virtual storage* 
whenever possible, throughout the assembly. 

• Two or more assemblies can be performed under the control of 
one set of job control language (JCL) cards. 

• Assembler H edits only the macro definitions that it 
encounters during a given macro expansion or during 
conditional assembly of open code, as controlled by AIF and 
AGO statements. 

• Source text assembly passes are consolidated. The edit and 
expansion of macro text are done on a demand basis in one pass 
of the source text. 

RESIDENT TABLES AND SOURCE TEXT: Performance is improved by 
keeping intermediate text, macro definition text, dictionaries, 
and symbol tables in main storage whenever possible. This reduces 
the I/O time required by assemblers that rely heavily on secondary 
storage throughout the assembly process. Less input/output 
reduces system overhead and frees channels and input/output 
devices for other uses. 

Certain portions must remain in virtual storage throughout the 
assembly process. The symbol table must remain resident, and it 
has no overflow capacity. Also, all partially filled blocks of 
text must remain resident. 

MULTIPLE ASSEMBLY-* Multiple or batch assemblies can be done under 
the control of a single set of JCL cards. Source decks are placed 
together, with no intervening "/*" card. 

Batch assembly improves performance by eliminating job and step 
overhead for each assembly. It is especially advantageous for 
processing related assemblies such as a main program and its 
subrout i nes. 

MACRO-EDITING PROCESS* Assembler H edits only those macro 
definitions that are encountered during a given macro expansion 
or during conditional assembly of open code, as controlled by AIF 
and AGO statements. 

A good example of potential savings by this feature is the process 
of system generation. During system generation, Assembler H edits 
only the set of library macro definitions that are expanded; as a 
result, Assembler H may edit up to 25% fewer library macro 
definitions than previous assemblers. 

CONSOLIDATING SOURCE TEXT PASSES* Consolidating assembly source 
text passes and other new organization procedures reduces the 
number of internal processor instructions used to handle source 
text in Assembler H. This is represented in proportionate savings 
in processor time. The saving is independent of the size or speed 
of the system processor involved; it is a measure of the relative 
efficiency of the processor. 
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AGO instruction 

alternate format 

extended 12 

tracing (see macro branch trace) 
AIF i nstruct i on 

alternate format 16 

extended 12 

macro AIF dump 25 

tracing (see macro branch trace) 
alternate format 16, 19 
AMODE attribute 1, 19 
arbitrary language input (AREAD) 8 
AREAD input affecting forward scan 

(see forward attribute reference) 
AREAD instruction 8 
arithmetic expressions, using SETC 

variables in 14 
assembler data set names, changing at 

system generation 4 
Assembler H internal design 2 
Assembler operations, revised 

CNOP instruction 18 

COPY instruction 18 

EQU instruction 18 

ISEQ instruction 18 

OPSYN instruction 18 
Assembler options, defaults for 4 
associative memory facility 

(see created SET symbols) 
attribute reference 

forward 15 

resolving (see internal design) 
attribute references 

defined attribute (D') 16 

number attribute (N') for SET 
symbols 16 

with SETC variables 15 
auxiliary storage space requirements 



number attribute (N f ) for SET 

Symbols 15 
with SETC symbols 15 
created SET symbols 13 
extended AIF instruction 
extended SETx instruction 
i d=xago . extended AGO instruction 
system variable symbols 

XSYSLIST with multilevel 

sublists 10 
&SYSL0C 17 

SSYSNDX, MHELP control on 
aSYSPARM 
conditional assembly extentions 

alternate format 16, 19 
continuation lines, number of 19 
COPY instruction 18 
created SET symbols 13 



11, 16 
12, 16 
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12 



Basic Assembler Language extensions 18 



data definition names 

changing DD names 4 

for Assembler H data sets 4 
data set requirements 2 
DD names 

(see data definition names) 
declaration of SET symbols 

dimensioned SET symbols 13 

implicit declaration 13 

multiple declaration 13 
default values for assembler options 4 
defined attribute (D') 16 
design, internal 2 
di agnost i cs 

extent i ons 23 

in regular assembly 23 
diagnostics in macro assembly 

error messages for library macros 24 

error messages for source macros 24 
dimension of SET symbol, maximum 13 
DSECT, referenced in Q-type address 

constant 22 
DXD, referenced in Q-type address 
constant 22 



CCWO instruction 1, 19 
CCW1 instruction 1, 19 
character variables used in arithmetic 

expressions 14 
CNOP instruction 18 
computed AGO instruction 

(see extended AGO instruction) 
conditional assembly extensions 
attribute reference 

defined attribute (D f ) 15 
forward 15 



E instruction type 1, 4 

editing inner macro definitions 7 

editing macro definitions 5 

EQU instruction 18 

error messages 

in general 23 

in library macros 24 

in source macros 24 
ESD 

(see external symbol dictionary) 
EXEC statement default options 4 
extended 

AIF instruction 11, 16 
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AGO instruction 12 
SETx instruction 12, 16 
Extended Architecture instruction 

set 1, 4 
extensions to basic assembler language 
(see Basic Assembler Language 
extensi ons) 
extensions to macro language 
i nstruct i ons 

(see conditional assembly extensions) 
(see macro language extensions) 
external 

symbol dictionary (ESD), restrictions 

on 22 
symbols, length of 20 
work f i le 3 



forward attribute reference 
forward scan 3 



15 



15 



GBLx instruction 

(see global SET symbol) 
generated macro operation codes 
generated statement 

attribute reference for 

error messages for 24 

format of 24 

sequence field of 23 
global SET symbol 

declaration 13 

suppression of (in MHELP options) 
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implicit declaration of SET symbols 
indirect addressing facility 

(see created SET symbols) 
i nner macro 

definition 7 

instruction 7 
input/output capability of macros 9 
installation requirements 2 
instruction sets 4 
instruction types 4 
internal design 2 
internal macro comments 11 
ISEQ instruction 19 
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language compatibility 1 
LCLx instruction 

(see local SET symbol) 
library macro, error messages for 
library space requirements 2 
local SET symbol 
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(see also implicit declaration of SET 
symbols) 

declaration 13 
location counter, multiple 20 
LOCTR instruction 20 
logic of Assembler H 

(see internal design) 
lookahead mode 

(see forward attribute reference) 
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machine requirements 2 
macro 

(see AREAD instruction) 

input/output capability of 9 

use of 5 
macro AIF dump 25 
macro branch trace 25 
macro call trace 25 
macro calls by substitution 7 
macro definition 

bypassing 5 

edi t i ng 5 

instructions allowed in 11 

nested 6 

placement 5 

redef i ni t i on of 6 
macro edi t i ng 

affecting performance 27 

for inner macro definitions 6 

i n general 5 
macro entry dump 25 
macro exit dump 25 
macro input 

(see AREAD instruction) 
macro input/output capability 9 
macro instruction 

nested 6 

nested with AREAD instructions 
macro instruction operation code, 

generated 7 
macro language extensions 

arbitrary language input, AREAD 

declaration of SET symbols 13 

instructions permitted in body of 
macro definition 11 

mnemonic operation codes redefined as 
macros 11 

nesting definitions 6 

placement of definitions 5 

redefinition of macros 6 

sequence symbol length 20 

substitution, macro calls by 7 

symbolic parameter length 

(see variable symbol length) 

variable symbol length 20 
macro name, length of 11 
macro trace 

(see MHELP instruction) 
main storage requirements 

(see virtual storage requirements) 
MHELP instructions 25 
mnemonic operation codes used as macro 

operation codes 11 
model statements permitted in macro 
def i n i t i ons 

(see macro definition, instructions 
allowed in) 
multilevel sublists 10 
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mult i pie assembly 27 

multiple declaration of SET symbols 

multiple location counters 20 



13 



RRE instruction type 1, 4 



nested COPY instructions 

(see COPY instruction) 
nested macro definitions 6 
nested subl i sts 

(see multilevel sublists) 
number attribute (N') for SET symbols 
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operating environment requirements 2 
operation codes for macros 

length of 11 

redefining 6 
operation codes, redefining conditional 
assembly 10 

(see also instruction sets) 
OPSYN instruction 

operation codes 18 

placement 18 

to redefine conditional assembly 
operations 10 

to rename macro 6 
options 

AREAD li sting 8 

assembler, setting defaults for 4 

MHELP 25 



parentheses, levels of, in 

expressions 20 
PARM field options 

(see Assembler options) 
performance 2 
processor requirements 2 
processor time 27 
program macro 

(see source macro, error messages for) 
PUNCH output capability 9 



Q-type address constant 22 



¥ 1 



redefining conditional assembly 

operation codes 10 
redefining macro names 6 
redefining standard operation codes as 

macro names 11 
RMODE attribute 1, 19 



sectioning and linking extensions 
multiple location counters 20 
no restrictions on ESD items 22 
Q-type address constants 22 
sequence checking 

(see ISEQ instruction) 
sequence field in macro-generated 

text 23 
sequence symbol length 11 
SET symbol 

created 13 
declarati on 

impl i ci t 13 
multiple 13 
dimensi on 

maximum 13 
specification 13 
SET symbol format and definition changes 
dimensioned SET symbols 13 
implicit declaration 13 
multiple declaration 13 
SET symbol length 

(see variable symbol length) 
SETC symbol 

attribute reference with 15 
in AREAD name field 

(see AREAD instruction 
in arithmetic expressions 14 
SETx instruction, extended 12, 16 
source macro, error messages for 24 
SSE instruction type 1, 4 
standard instruction sets 4 
statement numbers 1 
storage requirements 2 
sublists, multilevel 10 
substitution in macro instruction 

operation code 7 
symbol length 20 
symbol table 3 
symbolic parameter 

conflicting with created SET 

symbol 14 
length of 

(see variable symbol length) 
symbols 1 
syntax extensions 

character variables in arithmetic 

expressions 14 
continuation lines, number of 19 
levels of parentheses 

in macro instruction (see 
multilevel sublists) 
in ordinary assembler 
expressions 19 
number of terms in expression 20 
symbol length 20 
SYSLIST USYSLIST) wi th mult i level 

sublists 10 
SYSLOC USYSLOC) 17 

SYSNDX USYSNDX), MHELP control on 25 
SYSPARM USYSPARM) 4 
system generation, modifying the 

assembler at 3 
system macro 

(see library macro, error messages 
for) 
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system requirements 2 
system variable symbols 

&SYSLIST with multilevel sublists 10 

&SYSL0C 17 

&SYSNDX, MHELP control on 25 
System/370 instruction set 1, 4 
SYSUT1 3 



variable symbol length 20 
virtual storage requirements 



terms, number of, in expressions 20 

text passes, number of 2 

text processing 2 

tracing (see macro branch trace) 



work file 3 
working storage 



underscore character 1, 20 
Universal instruction set 1, 
ut i 1 i ty f i le 

(see SYSUT1 or work file) 
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